Really clean work — the module split (paths/store/resolver/client/errors) is well-layered and the test coverage is solid. A few things I noticed:

store.ts rename+chmod race — The write path does rename(tmp, path) then chmod(path, FILE_MODE). Between those two calls, the file briefly has whatever perms the renamed inode carried. Since you already chmod the tmp file before renaming, the post-rename chmod is only needed for the overwrite case where the destination had looser perms. You could drop the second chmod entirely and rely on the pre-rename one — rename atomically replaces the inode so the new file's permissions come from the tmp.

SOURCE_LABELS mismatch — status.ts hardcodes ~/.heygen/credentials.json in the label for file_json, but paths.ts defines CREDENTIAL_FILENAME = "credentials" (no .json extension). Users will see a misleading path in auth status output.

tryResolveCredential error check — Uses (err as { code?: string }).code === "NOT_CONFIGURED" instead of the isAuthError guard that's already imported nearby. Inconsistent and could match a non-AuthError with a .code property.

Rollback on fresh machine — If someone runs hyperframes auth login --api-key=bad_key on a fresh machine and the key fails verification, the rollback says "No previous credential to restore" and leaves the invalid key on disk. Deleting the file entirely seems like the better default here — you don't want a stale bad key sitting in the store.

Missing cli.mdx docs — CLAUDE.md checklist requires new commands to be documented in docs/packages/cli.mdx. Didn't see that in the diff.

None of these are blockers, solid PR overall.

Suggested status: Request changes.

Findings:

• Blocking: rollback() leaves the newly-written rejected key on disk when there was no previous credential. The write happens before verification (packages/cli/src/commands/auth/login.ts:73), and the empty-previous branch only logs No previous credential to restore (packages/cli/src/commands/auth/login.ts:105). For a first-time user who mistypes a syntactically valid hg_... key, auth login --api-key exits failure but future auth status still resolves the rejected key. Please delete the store or restore true absence when previous was empty, and add a regression test for invalid first login.
• Cleanup before merge: several user-facing hints still say ~/.heygen/credentials.json even though credentialPath() writes ~/.heygen/credentials (packages/cli/src/auth/errors.ts, packages/cli/src/commands/auth/status.ts). That will send users to the wrong file when troubleshooting.

All findings addressed:

• rename+chmod race fixed (chmod before rename, no post-rename chmod)
• SOURCE_LABELS now shows correct path without .json
• Rollback deletes store on fresh machine instead of leaving bad key
• cli.mdx docs added

Clean.

Suggested status: Request changes.

Prior blockers look fixed: failed first-login rollback now deletes the rejected credential, and user-facing paths now consistently point at ~/.heygen/credentials.

Blocking issue:

• packages/cli/src/auth/client.ts:130 - the scrubber only consumes one non-space token after Authorization:, so an echoed header such as Authorization: Bearer at_secret_123 becomes authorization: <redacted> at_secret_123. That still leaks opaque bearer tokens through safeText() into auth status --json / CLI errors. Please redact the whole header value, including bearer scheme plus token, and add a regression that asserts the token after Bearer is absent.

Scrubber fix looks good — HEADER_LINE now redacts to end-of-line, regression test covers the Bearer leak. Clean.

Suggested status: Approve.

Re-review of bb59411: prior blockers are fixed. Failed first-login rollback now removes the rejected credential, user-facing credential paths are corrected, and the Authorization header scrubber now redacts the full header value including Bearer <token> with regression coverage.

Verification run locally with Node 22 in PATH:

• bun run --filter @hyperframes/cli test -- src/auth/client.test.ts src/commands/auth/login.test.ts src/auth/store.test.ts
• bunx oxfmt --check on touched auth/login files
• bunx oxlint on touched auth/login files

Solid credential management. Security is the strongest part:

• tmp-then-rename writes with 0600/0700 permissions
• Header-injection guards via isHeaderSafe on all credential paths
• scrubCredentials strips keys/tokens/JWTs from error output
• Login rollback on 401 (restore previous state or delete)
• Legacy plaintext format handled on read, upgraded on write

CLI patterns followed correctly (defineCommand, examples, help groups, docs). Resolver chain (env vars → file) is clean with typed errors. 45 tests covering store I/O, rollback, and scrubbing.

Minor: logout exits with code 1 on user abort — code 0 would be more conventional for a non-error case.

Late-stage staff-level pass on a security-sensitive PR. Posting as a comment, not requesting changes — both Vance and Miguel have already approved and these are findings worth landing as follow-ups, not merge blockers.

The library design is clean: tight separation between paths / store / resolver / client / errors, all dependencies point inward, no dynamic_import / require patterns inside exit handlers, ESM stays static. File-mode hardening (0600 / 0700 with explicit chmod after temp-rename), header-injection guard via isHeaderSafe, the verify → rollback-on-401 / keep-on-network-blip policy, the credential scrubber on error bodies, and the typed AuthError discriminant are all the right shapes for an auth surface.

Blockers: none.

Important

1. The "shared with heygen-cli" claim is not currently true — this PR breaks heygen-cli sessions until heygen-cli#154 lands

docs/packages/cli.mdx:865 advertises "Credentials are stored in ~/.heygen/credentials … and are shared with the heygen CLI — sign in with one and the other picks up the session."

I read heygen-com/heygen-cli/internal/auth/file_resolver.go at HEAD:

// Resolve returns the API key from the credentials file…
data, err := os.ReadFile(path)
…
key := strings.TrimSpace(string(data))
…
return key, nil

heygen-cli treats the entire trimmed file contents as the API key. After a user runs hyperframes auth login --api-key, their ~/.heygen/credentials becomes:

{
  "api_key": "hg_real_key"
}

The next heygen-cli invocation will literally send x-api-key: { "api_key": "hg_real_key" } and either fail at the local header-validator or 401 at the API. Failure mode: a hyperframes user silently signs themselves out of heygen-cli with no warning and no path back to the legacy format short of rm ~/.heygen/credentials && heygen auth login.

The PR description acknowledges this — "PR 4 (heygen-cli read-side JSON support) follow" maps to heygen-cli#154, which is still open. Options I'd consider:

• Merge order: gate this PR on heygen-cli#154 being merged + released first. Lowest-risk path.
• Lockstep release: bundle hyperframes#1081 and heygen-cli#154 in the same release window; if both ship together, the breakage window collapses.
• Defer the JSON write: keep writeStore emitting the legacy single-line format for the api-key-only case until heygen-cli with JSON-read support is the floor. The JSON format only really pays for itself once OAuth (hf#1084) ships, which is also still open.

If none of those are practical, at minimum soften the docs claim ("read by heygen CLI once heygen-cli ≥ X.Y is installed") so users aren't surprised.

This is the one finding I'd push back on hardest — it has a real, reproducible user-visible failure mode.

2. No tests for auth status or auth logout

packages/cli/src/commands/auth/login.test.ts exercises the rollback contract on login carefully — good. But:

• status.ts is 200 lines of resolve + verify + format logic (--json, --human, source labels, OAuth expiry rows, billing rows, the credit-row resets_at slice, the unconfigured / API-error / non-AuthError-bubble branches) — zero tests.
• logout.ts covers --keep-api-key, the TTY confirmation prompt, the env-credential warning, and --yes — zero tests.

Failure modes worth covering at command level: status exit code (the contract is "scripts can check sign-in state with $?"), the --keep-api-key path that calls clearOAuth (versus the full deleteStore), and the env-var warning when HEYGEN_API_KEY is set during logout (since logout can't clear envs, missing this warning is a real UX trap).

3. Credential scrubber doesn't cover all advertised key formats

packages/cli/src/auth/client.ts:138-148 scrubs hg_*, Authorization: <anything> / x-api-key: <anything>, and JWTs. The codebase explicitly documents (and the legacy plaintext test cases include) other formats:

packages/cli/src/auth/store.ts:240-247:

"HeyGen API keys come in multiple formats (sk_V2_…, historic hg_…, partner keys, etc.)"

So the scrubber is partial defense in depth: the header-name-anchored regex catches everything when proxies echo headers (which is the common case), but a bare sk_V2_… token appearing in an error body without a header-name prefix would survive scrubbing.

Suggest either: extend the prefix list to hg_|sk_V2_|sk_[A-Za-z0-9]+_, or anchor the scrub entirely on header-name patterns and accept that bare-token echoes are a backend concern. Either is fine; what's there today is incomplete relative to the documented threat model.

Nits

• PR description says credentials.json; actual file is credentials (no extension, to match heygen-cli). Worth a one-line fix in the description since that's what merge-readers see.

• login.ts:144 mislabels the verify credential as source: "file_json". The source field isn't used by getCurrentUser, so this is harmless today, but it's a smell. Consider making source optional on ResolvedCredential, or adding a "verify" literal — it'll save someone confusion when this code is read in six months.

• Orphan .tmp files: writeStore uses ${path}.${pid}.${ts}.tmp then rename. A SIGKILL or process crash between writeFile(tmp) and rename leaves a credentials.<pid>.<ts>.tmp in ~/.heygen indefinitely. Tiny but accumulates and contains the plaintext credential. A best-effort unlink sweep of credentials.*.tmp at the start of writeStore would be ~5 lines.

• OAuth without expires_at is treated as fresh indefinitely (resolver.ts:103: const expired = expiresAt !== undefined && …). A token written without an expiry field is presumed valid forever. The 401 path recovers, but consider rejecting at parse time, or assuming-expired in the absence of expires_at, so the contract is clearer.

• Windows path is ~/.heygen, not %APPDATA% — deliberate to match heygen-cli, and the 0600/0700 chmod is a Unix concern (the store test correctly skips mode assertions on win32). Worth a one-line paths.ts comment noting that Windows users get the same path layout intentionally, since otherwise it looks like a portability oversight.

• Write-before-verify window: login.ts:88 writes the new key, then verifies. A SIGKILL between write and verify leaves an unverified key on disk. The rollback contract holds for the 401 path, but a verify-with-transient-credential-then-write-on-success ordering would close the window. Low priority — the user-visible contract still holds via the rollback path.

Architecture and security posture look solid overall. The 0600/0700 mode handling, the header-injection guard, the typed AuthError codes, the rollback-on-401, the credential scrubber, and the test discipline on the library side are all the right shapes. The cross-CLI compatibility claim is the one place where the docs are running ahead of reality, and that's the one I'd want to see resolved before users see this in a release.

— Vai